Add docs about sizing pictures

Suggested by Christopher Davis.

diff --git a/gtk/gtkpicture.c b/gtk/gtkpicture.c
index 78e5ba449a4c3e3df8dfc26a381b664ffe1e8ce4..bd4d9a91bba927f76cc08cfabbc99e2b4fd078e4 100644 (file)
--- a/gtk/gtkpicture.c
+++ b/gtk/gtkpicture.c
@@ -56,6 +56,18 @@
  * In this case, gtk_picture_new_for_resource() and gtk_picture_set_resource()
  * should be used.
  *
+ * # Sizing the paintable
+ *
+ * You can influence how the paintable is displayed inside the #GtkPicture. 
+ * By turning off GtkPicture::keep-aspect-ratio you can allow the paintable
+ * to get stretched. GtkPicture::can-shrink can be unset to make
+ * sure that paintables are never made smaller than their ideal size - but be
+ * careful if you do not know the size of the paintable in use (like when
+ * displaying user-loaded images). This can easily cause the picture to grow larger
+ * than the screen. And GtkWidget::halign and GtkWidget::valign can be used
+ * to make sure the paintable doesn't fill all available space but is instead
+ * displayed at its original size.
+ *
  * # CSS nodes
  *
  * GtkPicture has a single CSS node with the name picture.